home *** CD-ROM | disk | FTP | other *** search
/ BMUG Revelations / BMUG Revelations.toast / Utilities / Text and Speech / Speaker1.14 / Read Me < prev    next >
Text File  |  1994-05-18  |  11KB  |  363 lines

  1. With the availability of the Speech Manager, i found few applications which could
  2. take advantage of it.  Since none are currently readily available, i decided to
  3. make my own!
  4.  
  5.  
  6. Speaker 1.14 is a no-frills text editor, with speech capabilities, which works 
  7. with TEXT files.  Speaker will _NOT_ work without Apple's Speech Manager.  So
  8. far, the only place i know this is available from (aside from developer CD's)
  9. is the internet at ftp.apple.com
  10.  
  11.  
  12.  
  13. Getting Speaker to Speak
  14. ------------------------
  15.  
  16. Speaker has several different speaking modes. 
  17.  
  18. Note: Large voices such as the Macintalk Pro voices, require lots and lots
  19. of memory.  From my experience, at least 5 megabytes.  This space is taken
  20. by System meory, by the Speech Manager, so it is not necessary to change the
  21. memory size of Speaker.  Just have the memory available (i.e. around 
  22. 2.5 megabytes of unused memory showing in the About This Macintosh dialog from
  23. the Finder).  Compressed voices take up much less memory.
  24.  
  25.  
  26.  
  27. Speaking by Return Key
  28.  
  29. The first speaking mode is by the Return key.  Whenever you type something
  30. and press return, Speaker will say the line you just typed.  If you press 
  31. Return on a blank line, Speaker will repeat whatever was last spoken. If the
  32. insertion cursor is moved to a line with text, and the return key is pressed,
  33. the line which the cursor is in will be spoken.
  34. To disable this speaking mode, toggle the Disable Speech item under the Voice
  35. menu.
  36.  
  37.  
  38.  
  39. Speaking by Line
  40.  
  41. The next speaking mode is by line. Choose Speak Line from the File menu (or
  42. command L) and the line in which the cursor is located will be spoken.
  43.  
  44.  
  45.  
  46.  
  47. Speaking by File
  48.  
  49. To speak the entire file, choose Speak File from the File menu (or command F).
  50.  
  51.  
  52.  
  53. Speaking by Selection
  54.  
  55. To speak by selection, select the desired text to be spoken.  Choose Speak 
  56. Selection from the File menu (or command I).
  57. In addition, you may place the insertion point anywhere in your document
  58. and choose Speak Selection.  All text from the insertion point to the
  59. end of the document will be spoken.
  60.  
  61.  
  62.  
  63. Speaking via Apple Events (Programmers only!)
  64.  
  65. To speaker via AppleEvents, send an AppleEvent to Speaker with the following attributes:
  66.  
  67. Event Class:    kSpeechEventClass    
  68. Event ID:    kAESpeakText
  69.  
  70. These are defined via:
  71. #define kSpeechEventClass 'SPEK'
  72. #define kAESpeakText 'Say '
  73.  
  74. Thus, your call to AECreateAppleEvent will look something like this:
  75. err=AECreateAppleEvent(kSpeechEventClass,kAESpeakText,&target,kAutoGenerateReturnID,
  76.                             kAnyTransactionID,&appleevent);
  77.  
  78. After creating the AppleEvent, use AEPutParamPtr to add a parameter of the following attr:
  79.  
  80. keyword: keyDirectObject
  81. type:    typeChar
  82.  
  83. Thus, your call to AEPutParamPtr will look something like this:
  84. err=AEPutParamPtr(&theEvent,keyDirectObject,typeChar,thetext,length);
  85.  
  86. thetext represents a pointer to the text, and length is the length of the text.
  87. Note: The limit of the text legnth is 32768 bytes!
  88.  
  89. Finally, when sending the AppleEvent via AESend, do not request a reply--you won't get one!
  90. the call looks something like:
  91.     err=AESend(&theEvent,&reply,kAENoReply+kAENeverInteract,kAEHighPriority,
  92.                 kAEDefaultTimeout,idleproc,nil);
  93.  
  94.  
  95.  
  96. Aborting Speech
  97.  
  98. Speech can be abored by clicking the mouse.
  99.  
  100.  
  101.  
  102.  
  103. Changing Voice, Pitch, and Rate
  104. -------------------------------
  105.  
  106. Change the voice, pitch, or rate by choosing the corresponding item from under the
  107. Voice menu.
  108.  
  109. Note: Some voices are a little picky about pitch and rate.  Thus, values will
  110. be rounded to the nearest amount which the voice will accept.
  111.  
  112. In the event that voices are added or removed while Speaker is running, use the
  113. Update Voices menu choice to update the voice list.
  114.  
  115. Saving the Default Voice
  116.  
  117. If there is a particular voice which you want to be automatically selected when
  118. Speaker is launched, save the voice as the default.
  119. To save the default voice: 1.  Choose the voice. 2. Select "Save Default Voice" from
  120. the voice menu.
  121.  
  122.  
  123.  
  124. Preferences
  125. -----------
  126.  
  127. Speaker can now automatically speak a) files which are openned from the finder (i.e.,
  128. drag and drop) or b) files which are openned via the File menu.
  129.  
  130.  
  131.  
  132.  
  133. Dictionaries
  134. ------------
  135.  
  136. Sometimes, words are mispronounced.  Dictionaries help alleviate this problem
  137. by allowing you to specify the correct proununciation through the use of phonemes.
  138.  
  139. Phonemes are symbolic representations of the various, common sounds found in 
  140. speech.  For example, "bout" and "how" have the same 'o' sound, even though they
  141. are spelled diferently.  Thus, the same phoneme would be used to represent this
  142. 'o' sound.
  143.  
  144. Dictionary information is kept in a file called "Dictionary." This allows
  145. you to use other people's dictionaries, fairly easily, by replacing this
  146. file with the new dictionary.  In the future, i may add an import capability
  147. or something, but i hope the current configuration is good enough for now.
  148.  
  149.  
  150.  
  151. To enter a new Dictionary entry:
  152.  
  153. 1. Type in the word to convert in the text field.
  154.    Note:Avoid using capital letters. The Macintalk Pro voices don't seem to like
  155.    them.
  156.    
  157. 2. Click on the Convert button.
  158.    This button converts the word you typed into phonemes. This will be the speaker's
  159.    "best guess".  This button alleviates the need of making a phoneme
  160.    from scratch.
  161. 3. Edit the Phoneme.
  162.    See below for a summary of phonemes and other codes.
  163. 4. Click on the Speak It button to test the pronunciation of the word.
  164. 5. When you are satisfied, click on the New button.
  165.    If an entry has already been made, under the exact same word, The Speaker
  166.    beep because it does not allow duplicate dictionary entries.
  167.    
  168.    
  169.  
  170. To change a Dictionary Entry:
  171.  
  172. 1. Click on the Dictionary Entry in the Entry list.
  173. 2. Change either the word itself, or the phoneme which represents it.
  174. 3. Test the pronunciation with the Speak It button.
  175. 4. When satisfied with the changes, click on the Replace button.
  176.  
  177.  
  178.  
  179. To delete a Dictionary Entry:
  180.  
  181. 1. Click on the Dictionary Entry in the Entry list.
  182. 2. Click on the Delete button.
  183.  
  184.  
  185.  
  186.  
  187. There is a limit of 256 character for dictionary entries and their phoneme counterparts.
  188.  
  189. Memory cavaet!  If The Speaker is unsuccessful in loading the speech channel (usually
  190. because there is not enough memory) the Convert to phonemes and Say It functions will
  191. not work! This is very, very very true when you try to use the Macintalk Pro voices
  192. which take up gobs and gobs of memory!
  193.  
  194. Technical Notes
  195. ---------------
  196.  
  197. For programmers interested in the dictionaries used in The Speaker:  The dictionary
  198. resource is of type 'dict' and is id #128.  Just use ResEdit to copy it out.
  199.  
  200. Currently, The Speaker's dictionary resources are modeled after the example dictionary
  201. Rez file which came with the Speech Manager. Thus, (in case you're importing 
  202. dictionaries into the Speaker) it does not support abreviation entries, and accepts
  203. no more and no less than two fields per entry, the first one begin the text 
  204. representation, the second being the phoneme.
  205.  
  206. Also, you might notice the dictionary list is not sorted.  Version 1.11 now sorts
  207. the list.  Unfortunately, i only implemented a selection sort, which is kinduv slow.
  208. Thus, the request is still here for some nice quicksort code, which sorts an array
  209. of n items of any size.
  210.  
  211.  
  212. Phonemes Codes and Prosodic Controls
  213. ------------------------------------
  214.  
  215. More information on Phonemes can be found in the Speech Manager Documentation,
  216. available at ftp.apple.com, in the same directory as the Speech Manager itself.
  217.  
  218. Note:  Phoneme codes are case sensitive!
  219.  
  220. Phoneme            Example                    Phoneme            Example
  221. -------            -------                    -------            -------
  222. AE                h<a>t                    g                <g>reat
  223. EY                g<a>te                    h                <h>ope
  224. AO                b<au>ght                J                <j>oke
  225. AX                <a>gast                    k                <c>ool
  226. IY                m<ee>t                    l                <l>oom
  227. EH                m<e>t                    m                <m>ace
  228. IH                b<i>t                    n                <kn>ock
  229. AY                b<i>te                    N                ba<ng>
  230. IX                clos<e>s                p                <p>ing
  231. AA                l<o>t                    r                <wr>ong
  232. UW                l<oo>t                    s                <s>atin
  233. UH                c<oo>k                    S                <sh>oes
  234. UX                m<u>d                    t                <t>alk
  235. OW                <oa>t                    T                <th>eme
  236. AW                b<ou>t                    v                <v>isit
  237. OY                t<oy>                    w                <w>alk
  238. b                <b>eam                    y                <y>ank
  239. C                <ch>oke                    z                <z>ebra
  240. d                <d>ark                    Z                <j>aque        <g>enre
  241. D                <th>ose                    %                silence
  242. f                <f>ake                    @                breath intake
  243.  
  244. Examples:
  245.  
  246. Word:        Anticipation        Supercede
  247.  
  248. Phoneme:    AEntIHsIXpEYSAXn    _sUWpAXrsIYd
  249.  
  250.  
  251.  
  252. Posodic Codes
  253. -------------
  254.  
  255. These are used in conjunction with phonemes to fine tune pronunciation.
  256.  
  257.                     Code            Description
  258. Stresses            
  259.  
  260. Primary Stress        1                AEnt2IHsIXp1EYSAXn
  261. Secondary Stress    2                (anticipation)
  262.  
  263. Syllables
  264.  
  265. Syllable break        =                Breaks up word into Syllables
  266.                                     AEn=t2IH=sIX=p1EY=SAXn
  267.                                     (anticipation)
  268.  
  269. Word Prominence
  270.  
  271. Unstressed            ~
  272. Normal Stress        _ (underscore)
  273. Emphatic Stress        +
  274.  
  275. Prosodic
  276.  
  277. Pitch rise            /
  278. Pitch fall            \
  279. Lengthen phoneme    >
  280. Shorten phoneme        <
  281.  
  282.  
  283. Examples:
  284.  
  285. Anticipation
  286. AEn=t2IH=sIX=p1EY=SAXn
  287.  
  288.  
  289. Various punctuation marks further adjust timing and are sometimes useful
  290. when dealing with sentences.  See the Speech Manager documentation for more info.
  291.  
  292.  
  293. Macros and Embedded Speech Commands (advanced)
  294. ----------------------------------------------
  295.  
  296. Speaker allows you to save commonly used strings in a file named Speaker Macros.
  297. Every line in this file is considered a seperate macro.  Blank lines are ignored.
  298.  
  299. Currently, this file contains Speech Manager commands which can be embedded in
  300. spoken text to alter the way text is spoken.  Open the file named "Embedded Codes
  301. Demo" for various examples.
  302.  
  303. Macro lines have a limit of 256 characters.  There is a current Macro limit of
  304. 1000 (should be more than enough since i've never seen a menu with 1000 items
  305. in it!).
  306.  
  307. To re-read the macros file (in case it has/is changed while Speaker is running),
  308. choose the Re-Read File item from the Macros menu.  If you edit the file from
  309. within Speaker, you must close the file before re-reading it.
  310.  
  311.  
  312.  
  313.  
  314. Distribution
  315. ------------
  316.  
  317. You may non-commercially distribute this software provided all files that came
  318. with this archive remain intact, un-modified, and together.
  319.  
  320. Oh, and by the way, this software is FREE.  Have fun with it.
  321.  
  322.  
  323. Disclaimer
  324. ----------
  325.  
  326. There is no expressed waranty, etc, etc., etc.  Use this software at your own
  327. risk.
  328.  
  329. The purpose of this software is not to crash your machine, but if it trashes
  330. your hard drive which contains $1,000,000 worth of client data on it, and
  331. you don't have a backup (shame, shame!), don't come looking for me to collect
  332. damages.
  333.  
  334.  
  335. Nostalgia Note
  336. --------------
  337.  
  338. Back in the old days, when the Apple // was fairly prominent, there were a 
  339. couple programs that did similar stuff to the Speech Manager.  A neat one
  340. was called the Cat's Meow which worked with the good o'l Apple Cat modem, 
  341. and allowed you to transmit speech directly to the phone. Neat little toy.
  342.  
  343. The current Macintalk voices don't sound too much better than those generated
  344. on the 1982 Apple //....Hope Apple makes some better voices.
  345.  
  346.  
  347. Questions? Suggestions? Source Code needed?
  348. -------------------------------------------
  349.  
  350. If you have any questions, or suggestions, write me!  If you want source code,
  351. my only request is that you have an e-mail account on the internet (because this
  352. doesn't cost me $$), and that if you copy source code, ya give me a little
  353. credit (one of those option-command-control-drag-click menus/dialogs would
  354. be fine!).
  355.  
  356.  
  357. Internet: eshieh@cory.berkeley.edu
  358. Compuserve: 76164,765
  359. US Postal:
  360.  
  361. Eric Shieh
  362. P.O. Box 1235
  363. Danville, CA 94526